home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / LPC / functions < prev    next >
Text File  |  2001-04-06  |  6KB  |  159 lines
  1. CONCEPT
  2.         functions
  3.  
  4. DESCRIPTION
  5.         Functions are named blocks of code which are be called with
  6.         a number of argument values, and which return a result value
  7.         to the caller.
  8.  
  9.         Functions are defined in an object and are also known as
  10.         "local funs" or short "lfuns".
  11.  
  12.  
  13.         DEFINING A FUNCTION
  14.  
  15.         A function definition takes the form
  16.  
  17.           <modifiers> <type> name ( <arguments> ) {
  18.              statements...
  19.           }
  20.  
  21.         The parts in detail:
  22.           - <modifiers> can be any one of "static", "private", "public"
  23.               and "protected" (see modifiers(LPC)), optionally combined
  24.               with "varargs" (see varargs(LPC)) and/or "nomask".
  25.               If not specified, the function behaves as if it was
  26.               specified as "public", but this visibility can be restricted
  27.               in derived object through non-public inheritance.
  28.           - <type> is the type of the result returned by the function.
  29.               If specified as "void", the function is compiled to return
  30.               the value 0 under all circumstances. If not specified, the
  31.               type is assumed to be "mixed", furthermore typechecking is
  32.               disabled for this function.
  33.           - name is the name of the function, e.g. "short", or "Nice_Try",
  34.               under which it is made known.
  35.           - <arguments> is a list of variable definitions in the
  36.               normal '<type> <name>' style, separated by comma.
  37.               Examples: () : no argument taken
  38.                         (int a) : takes on integer argument
  39.                         (mixed a, object *b): takes two arguments, one
  40.                            arbitrary type, one array of objects.
  41.           - { statements... } defines the code for this function. This
  42.               is a normal block (see block(LPC)) and as such can define
  43.               its own local variables.
  44.  
  45.  
  46.         DECLARING A FUNCTION
  47.  
  48.         A function declaration makes the name and type of a function known
  49.         to the compiler with the assertion that the code for this function
  50.         will be provided "elsewhere".
  51.  
  52.         The form is:
  53.  
  54.           <modifiers> <type> name ( <arguments> );
  55.  
  56.         Typical uses are:
  57.           - to declare in advance functions which are called before they
  58.             can be defined; for example if the create() function of an object
  59.             calls other functions which are defined after the create().
  60.           - to declare functions which will be provided by an inheriting
  61.             object.
  62.  
  63.         Calling a declared but undefined function results in a runtime error.
  64.  
  65.  
  66.         CALLING A FUNCTION
  67.  
  68.         Functions in other objects are called with the call_other() efun,
  69.         which can be shortened to '->':
  70.  
  71.            ob->fun(a, b, c)
  72.            call_other(ob, "fun", a, b, c)
  73.  
  74.         Functions in the same object are called just by writing their name,
  75.         followed by the arguments in parenthesis:
  76.  
  77.            short()
  78.            compute(a)
  79.            do_that(a, "foo")
  80.  
  81.         If the number of values passed to the function does not match the
  82.         number of expected arguments (and if type checking is enabled), the
  83.         driver will perform the necessary adaption at call time: excess
  84.         values are ignored, missing values are substituted by the number 0.
  85.         The values passed to the called function are massaged by the driver
  86.         to match the argument list 
  87.  
  88.  
  89.         FUNCTIONS AND INHERITANCE
  90.  
  91.         A "public" or "protected" (== "static") function defined in one
  92.         object is also visible in all inheriting objects. The exception from
  93.         this rule is when an inheriting child redefines ("overloads") the
  94.         inherited function with its own. When compiling with type checking,
  95.         the argument list of the redefined function has to match the
  96.         original one.
  97.  
  98.         When a function is called, the driver looks for the function first
  99.         in the object called, and if not found there, then in the inherited
  100.         objects.
  101.  
  102.         To explicitely call an inherited function (useful when a redefining
  103.         functions wants to use the original one), the "::" operator is used:
  104.  
  105.             ::create()
  106.             ::compute(a)
  107.  
  108.         The named function is searched only in the inherited objects, and
  109.         the first found is used.
  110.  
  111.  
  112.         If the function is inherited from several objects and a specific
  113.         one is to be called, the "::" can be extended to contain the
  114.         partial or full name of the inherited object:
  115.  
  116.             inherit "/obj/cooker";
  117.             inherit "/obj/container";
  118.  
  119.             tainer::create()
  120.             container::create()
  121.             "tainer"::create()
  122.             "container"::create()
  123.             "obj/container"::create()
  124.             "/obj/container"::create()
  125.  
  126.         all call the create() in the container inherit. Note that the
  127.         name given to the :: operator is matched against the ends of
  128.         the inherited names.
  129.  
  130.  
  131.         One special form of this call is
  132.  
  133.             efun::find_object()
  134.  
  135.         which bypasses any redefinition of an efun (here find_object())
  136.         and directly calls the efun itself. This is only possible for
  137.         efun-redefinitions which do not use the "nomask" modifier.
  138.  
  139.  
  140.         Additionally, a call to a function inherited from several objects
  141.         can be instructed to call _all_ inherited functions through the
  142.         use of the wildcards "*" (match any number of arbitrary characters)
  143.         and "?" (match one arbitrary character):
  144.  
  145.             inherit "/obj/cooker";
  146.             inherit "/obj/container";
  147.  
  148.             "*"::create()
  149.             "co*"::create()
  150.             "*er"::create()
  151.  
  152.         all call both inherited create()s. The function called this way
  153.         must not take arguments, and the single results from all calls are
  154.         combined into one array used as final result.
  155.  
  156. SEE ALSO
  157.         types(LPC), modifiers(LPC), varargs(LPC), references(LPC),
  158.         call_other(E), simul_efun(C), call_out(E)
  159.